From 6241ae009ef6b97a5b5128083c8d79d78621fb36 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 1 Dec 2017 10:29:14 -0500 Subject: [PATCH] docs: Some revision to the migration docs Cover more of the recent changes, and revise some of the wording. --- docs/reference/gtk/migrating-3to4.xml | 111 +++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 11 deletions(-) diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml index e86139aa92..8031ea64c8 100644 --- a/docs/reference/gtk/migrating-3to4.xml +++ b/docs/reference/gtk/migrating-3to4.xml @@ -24,7 +24,7 @@ release of GTK+ 3.x. It includes all the necessary APIs and tools to help you port your application to GTK+ 4. If you are still using an older version of GTK+ 3.x, you should first get your application - to build and work with 3.22. + to build and work with the latest minor release in the 3.22 series.
@@ -56,7 +56,7 @@ Do not use widget style properties Style properties do not exist in GTK+ 4. You should stop using them in - your custom CSS. + your custom CSS and in your code.
@@ -85,6 +85,11 @@ GTK+ 4 always uses RGBA visuals for its windows; you should make sure that your code works with that. + + At the same time, you should stop using GdkVisual APIs, this object + not longer exist in GTK+ 4. Most of its APIs are deprecated already + and not useful when dealing with RGBA visuals. +
@@ -100,7 +105,7 @@ widgets. If you previously set the fill child property to %TRUE, you can achieve the same effect by setting the halign or valign properties to %GTK_ALIGN_FILL, depending on the parent box -- halign for a horizontal - box, valign for a vertial one. + box, valign for a vertical one. #GtkBox also uses the expand child property. It can be replaced by setting @@ -108,12 +113,13 @@ old behavior of the #GtkBox's expand child property, you need to set #GtkWidget:hexpand on the child widgets of a horizontal #GtkBox and #GtkWidget:vexpand on the child widgets of a vertical #GtkBox. - + + Note that there's a subtle but important difference between #GtkBox's expand and fill child properties and the ones in #GtkWidget: setting #GtkWidget:hexpand or #GtkWidget:vexpand to %TRUE will propagate up - the widget hierarchy, so a pixel-perfect port migth require a reset - of the expansion flags to %FALSE in a parent widget higher up the hierarchy. + the widget hierarchy, so a pixel-perfect port might require you to reset + the expansion flags to %FALSE in a parent widget higher up the hierarchy.
@@ -123,8 +129,8 @@ The getters in the GtkStyleContext API, such as gtk_style_context_get_property(), gtk_style_context_get(), or gtk_style_context_get_color() only accept the context's current - state for their state argument. Update all callers to pass the current - state. + state for their state argument. You should update all callers to pass + the current state. @@ -148,6 +154,33 @@ have been either impossible or impractical. +
+ Stop using GdkScreen + + The GdkScreen object has been removed in GTK+ 4. Most of its APIs already + had replacements in GTK+ 3 and were deprecated, a few remaining replacements + have been added to GdkDisplay. + +
+ +
+ Stop using the root window + + The root window is an X11-centric concept that is no longer exposed in the + backend-neutral GDK API. gdk_window_get_parent() will return %NULL for toplevel + windows. If you need to interact with the X11 root window, you can use + gdk_x11_display_get_xrootwindow() to get its XID. + +
+ +
+ Stop using GdkDeviceManager + + The GdkDeviceManager object has been removed in GTK+ 4. Most of its APIs already + had replacements in GTK+ 3 and were deprecated in favor of GdkSeat. + +
+
Adapt to GdkWindow API changes @@ -166,6 +199,15 @@
+
+ Stop accessing GdkEvent fields + + Direct access to GdkEvent structs is no longer possible in GTK+ 4. Some + frequently-used fields already had accessors in GTK+ 3, and the remaining + fields have gained accessors in GTK+ 4. + +
+
Adapt to GtkStyleContext API changes @@ -269,7 +311,7 @@ A number of APIs for querying special-purpose windows have been removed, since these windows are no longer publically available: - gtk_tree_view_get_pin_window(), gtk_viewport_get_bin_window(), + gtk_tree_view_get_bin_window(), gtk_viewport_get_bin_window(), gtk_viewport_get_view_window().
@@ -299,8 +341,55 @@
GdkPixbuf is deemphasized - A number of GdkPixbuf-based APIs have been removed. Use the available - surface-based replacements instead. + A number of GdkPixbuf-based APIs have been removed. The available replacements + are either using cairo_surface_t or the newly introduced GdkTexture class + instead. + + + If you are still dealing with pixbufs, you will likely want to use + gdk_texture_new_for_pixbuf() to convert them to texture objects where needed. + +
+ +
+ GtkWidget event signals are deemphasized + + GtkGesture classes have already been introduced in GTK+ 3 to handle input for + many cases. In GTK+ 4, even more are available, such as GtkEventControllerScroll. + +
+ +
+ The gtk_window_fullscreen_on_monitor() API has changed + + Instead of a monitor number, it now takes a GdkMonitor argument. + +
+ +
+ Adapt to cursor API changes + + Use the new gtk_widget_set_cursor() function to set cursors, instead of + setting the cursor on the underlying window directly. This is necessary + because most widgets don't have their own window anymore, turning any + such calls into global cursor changes. + + + For creating standard cursors, gdk_cursor_new_for_display() has been removed, + you have to use cursor names instead of GdkCursorType. For creating custom cursors, + use gdk_cursor_new_from_texture(). The ability to get cursor images has been removed. + +
+ +
+ Adapt to icon-size API changes + + Instead of the existing extensible set of symbolic icon sizes, GTK+ now only + supports normal and large icons. The actual sizes can be defined by themes via + the CSS property -gtk-icon-size. + + + The GtkCellRendererPixbuf::stock-size property has been renamed to ::icon-size.
-- 2.30.2